Script hook

Over the years, Cadmatic has created a number of script hooks that allow the user organizations to interface application events that normally cannot be interfaced. These actions are automated to occur whenever a user invokes a specific command in a specific context, but only if the given script hook is present in the environment. For example, starting to create a new drawing or diagram can trigger a script hook to get the header data of the document from a Document Management System (DMS).

Originally, script hooks were separate files that Cadmatic distributed upon request, but now they are part of the software installation and managed via the COS databases. Be aware that if your environment still has old script hook files in PMS_HOME/opt/<app>/ScriptHooks.cnf folders, then they are going to be used instead of the ones in COS.

In the Project Environment dialog, the project administrator can take a script hook into use by creating a configuration for it and marking it as enabled. A script hook configuration that is created in the library database can be approved for use in projects.

In a script hook configuration, the administrator links the script hook to a matching function in a script that either Cadmatic or the user organization has created. Besides being able to automate specific background actions, script hooks have the benefit of allowing all the variables of the associated script to remain available after the script has stopped running (until the application session ends). Although each script hook has been written for a specific purpose, the variables which the associated scripts expose to the session can in principle be used by any other script function in the same script file.

This is how script hooks work in Plant Modeller, Piping Isometrics & Spools, and P&ID:

The user invokes a command that has the ability to use a script hook. The context where this happens is always predefined; only Cadmatic can add script hooks to application commands.
The script hook starts the script that is defined in the script hook configuration. If the script hook has input arguments, the script hook assigns the values of these input arguments in the associated script function.
The script runs its course and returns a value to the script hook. If the script function has output arguments, their values are assigned to the output arguments of the script hook.
The output arguments and the return value define the effect to the invoked command. For example, the command may continue execution with the new or changed data that it received from the script hook, or the script hook may indicate that the command should stop.

If the script hook is not found or is not enabled for use, then the invoked command simply does what it normally does.

Creating a script hook configuration

Create a script hook configuration that links a script hook to a script, so that triggering the script hook in the application will cause the associated script to be run.

As each script hook configuration is named after the script hook, there can be several configurations with the same name, but only one of them can be enabled at a time.

Prerequisites

COS contains a script (see Scripts) where a function has arguments that match those of the script hook. If you are working in the library database, also the script must be in the library database. If you are working in the project database, you can select the script from the library or the project database.

Do the following:

In the Project Environment dialog, in [library or project] > Resources > Script Hook, select New > Script Hook. The Script Hook Editor dialog opens.

Show/hide image
In the Hook name fields, first select the application and then the application-specific script hook.
In the Script section, define how to use the script hook:
- Script – Click Browse to select the script that the script hook is to run.
- Function – Select the script function that the script hook is to interact with.
- Enable – Select this option to enable the script hook.
Click OK.

Script hooks for Plant Modeller

These script hooks exist for the scripts of the Plant Modeller application.

Name	Purpose	Context	Input arguments	Input/Output arguments	Output arguments	Return values
PmScH_AboutToCheckInDrawing	Specifies the Object ID, the name, and the header data of the document to be checked in, and returns (possibly modified) header data to the script hook.	Called when about to check in the active drawing or a new drawing, before saving the drawing locally.	COS OID of document document name	handle to header data tag record	–	0: allow check-in negative value: deny check-in
PmScH_AfterDrawingConversion	Specifies the Object ID, the name, and the header data of the document to be checked in.	Called when a user is trying to open a drawing for the first time, after the drawing has been converted from the old format to the current format.	COS OID of document document name handle to header data tag record	–	–	0: success negative value: failure
PmScH_CheckInDrawing	Specifies the Object ID, the name, and the header data of the document to be checked in.	Called when checking in a drawing, after PmScH_AboutToCheckInDrawing has been called and a local save has been done.	COS OID of document document name handle to header data tag record	–	–	0: allow check-in negative value: deny check-in
PmScH_DeleteStandcmp	Specifies the index of the Standard Component to be deleted.	Called when deleting a Standard Component that has user-defined associations.	index of component to delete	–	–	(no effect to the context)
PmScH_DoFlangeValidation	Checks which flanges in the pipeline specifications of the active pipeline are suitable in the current context (for example, based on pressure and temperature).	Called in the following contexts (a–d), if the pipeline has the attribute "Execute flange validation" set to "Yes": The user selects a command from Piping > Flange Set > Insert. The user selects a command from Piping > Standard Component > Insert. The user selects Piping > Route and starts or ends a new pipe at a flanged connection. The user selects Add component during pipe routing and inserts a component with at least one flanged node.	Validation context a–d Pipeline name Object ID of piping part where flange is inserted in contexts a and b or Part ID of model object where routing begins in context c Part ID of previous model object in context d Node ID of node where routing begins or ends in context c Functional code of flange to use, such as "f1" (output)	–	–	1–5: index of pipeline specification 0: no effect to the context negative value: failure
PmScH_DrawingDeleted	Specifies the name of the document to be deleted.	Called when about to delete a drawing.	document name	–	–	0: allow deletion negative value: deny deletion
PmScH_GetCustomBrowserActionsForDrawings	Specifies the COS object type of the document object in question. Can be used to add context-menu commands to the document object browser.	Called when opening an object browser to manage drawings of a specific type, such as Plant Modeller Drawings or Duct Main Documents.	COS object type of document object	–	–	data record of commands to add to the right-click menu
PmScH_GetInfoForNewDrawing	Gets header information for a new drawing.	Called when about to create a new drawing.	–	–	name of new document handle to header data tag record	0: allow creation negative value: deny creation
PmScH_GetNodeWeldId	Customize the value of the weld ID attributes that are assigned to object connection points.	Called when creating isometric groups, before the weld ID attribute is assigned to the object connection point.	Object handle Node ID	Weld ID	–	0: weld ID OK -1: prevent adding any weld ID to the object connection point
PmScH_PublishDrawing	Specifies the Object ID of the document to be published.	Called when publishing a drawing.	COS OID of publication object	–	–	(no effect to the context)
PmScH_OkToRelocateSet	(This script hook is obsolete.)	Called when moving a set of objects and some of them have user-defined associations.	handle of the object set	–	–	0: allow move negative value: deny move
PmScH_RelocationAccepted	(This script hook is obsolete.)	Called from the script extern PM_RELOCATION_ACCEPTED when relocating a set of objects has been accepted.	–	–	–	the return value for the script extern PM_RELOCATION_ACCEPTED
PmScH_RelocationRejected	(This script hook is obsolete.)	Called from the script extern PM_RELOCATION_REJECTED when relocating a set of objects has been rejected.	–	–	–	the return value for the script extern PM_RELOCATION_REJECTED

Script hooks for Piping Isometrics & Spools

These script hooks exist for the scripts of the Piping Isometrics & Spools application.

Name	Purpose	Context	Input arguments	Input/Output arguments	Output arguments	Return values
PiScH_AboutToCheckInIsometricDrawing	Specifies the Object ID, the name, and the header data of the document to be checked in.	Called when about to check in an isometric drawing, before a local save.	COS OID of document document name handle to header data tag record	–	–	0: allow check-in negative value: deny check-in
PiScH_CheckInIsometricDrawing	Specifies the Object ID, the name, and the header data of the document to be checked in.	Called when checking in an isometric drawing, after PiScH_AboutToCheckInIsometricDrawing has been called and a local save has been done.	COS OID of document document name handle to header data tag record	–	–	0: allow check-in negative value: deny check-in
PiScH_CheckOutIsometricDrawing	Specifies the Object ID, the name, and the header data of the document to be checked in.	Called when about to edit an isometric drawing.	COS OID of document document name handle to header data tag record	–	–	0: allow check-out negative value: deny check-out
PiScH_GetCustomBrowserActionsForIsometricDrawings	Specifies the COS object type of the document object in question. Can be used to add context-menu commands to the document object browser.	Called when opening an object browser to manage isometric drawings.	COS object type of document object	–	–	data record of commands to add to the right-click menu
PmScH_IsometricDrawingDeleted	Specifies the Object ID of the document to be deleted.	Called when about to delete an isometric drawing.	COS OID of document	–	–	0: allow deletion negative value: deny deletion
PiScH_PublishDrawing	Specifies the Object ID of the document to be published.	Called when publishing an isometric drawing.	COS OID of publication object	–	–	(no effect to the context)

Script hooks for P&ID

These script hooks exist for the scripts of the P&ID application.

Name	Purpose	Context	Input arguments	Input/Output arguments	Output arguments	Return values
PdScH_AboutToCheckInDiagram	Specifies the GUID, the name, and the header data of the diagram to be checked in.	Called at the beginning of saving a diagram that is to be checked in.	COS OID (GUID) of diagram diagram name handle to header data tag record	–	–	0: allow check-in negative value: deny check-in
PdScH_AboutToCheckOutDiagram	Specifies the GUID and the name of the diagram to be checked out.	Called when about to check out a diagram.	COS OID (GUID) of diagram diagram name	–	–	0: allow check-out negative value: deny check-out
PdScH_CancelCheckOutDiagram	Specifies the GUID and the name of the diagram whose check-out is to be canceled.	Called when about to cancel the check-out of a diagram.	COS OID (GUID) of diagram diagram name	–	–	0: allow canceling the check-out negative value: deny canceling the check-out
PdScH_CheckInDiagram	Specifies the GUID, the name, and the header data of the diagram to be checked in, and returns (possibly modified) header data to the script hook.	Called when checking in a diagram, after PdScH_AboutToCheckOutDiagram has been called and a local save has been done.	COS OID (GUID) of diagram diagram name	handle to header data tag record	–	0: set modified header data from script hook negative value: deny modified header data from script hook
PdScH_CheckOutDiagram	Specifies the GUID, the name, and the header data of the diagram to be checked out, and returns (possibly modified) header data to the script hook.	Called when checking out a diagram.	COS OID (GUID) of diagram diagram name	handle to header data tag record	–	(no effect to the context)
PdScH_DiagramDeleted	Specifies the GUID of the diagram to be deleted.	Called when about to delete a diagram.	COS OID (GUID) of diagram	–	–	0: allow deletion negative value: deny deletion
PdScH_GetCustomBrowserActionsForDiagrams	Specifies the COS object type of the document object in question. Can be used to add context-menu commands to the document object browser.	Called when opening an object browser to manage diagrams.	document COS object type	–	–	data record of commands to add to the right-click menu
PdScH_GetInfoForNewDiagram	Gets the header data for a new diagram and returns (possibly modified) header data and the name of the new diagram to the script hook.	Called when about to create a new diagram.		handle to header data tag record	diagram name	0: allow creation to continue negative value: deny creation
PdScH_PublishDiagram	Specifies the GUID of the new diagram publication.	Called after creating a new diagram publication.	COS OID (GUID) of publication object	–	–	(no effect to the context)